home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / c++ / sbuf.pub.z / sbuf.pub
Encoding:
Text File  |  2002-10-03  |  12.0 KB  |  225 lines
  1. SBUF.PUB(3C)                                         Last changed: 10-20-98
  2.  
  3.  
  4. NNAAMMEE
  5.      ssttrreeaammbbuuff - Public interface of character buffering class
  6.  
  7. SSYYNNOOPPSSIISS
  8.      ##iinncclluuddee <<iioossttrreeaamm..hh>>
  9.  
  10.      ttyyppeeddeeff lloonngg ssttrreeaammooffff,, ssttrreeaammppooss;;
  11.      ccllaassss iiooss {{
  12.      ppuubblliicc::
  13.           eennuumm sseeeekk__ddiirr {{ bbeegg,, ccuurr,, eenndd }};;
  14.           eennuumm ooppeenn__mmooddee {{ iinn,, oouutt,, aattee,, aapppp,, ttrruunncc,, nnooccrreeaattee,, nnoorreeppllaaccee }}
  15.      ;;
  16.           //// aanndd lloottss ooff ootthheerr ssttuuffff ...... SSeeee iiooss((33CC))
  17.      }} ;;
  18.  
  19.      ccllaassss ssttrreeaammbbuuff {{
  20.      ppuubblliicc ::
  21.  
  22.           iinntt       iinn__aavvaaiill(());;
  23.           iinntt       oouutt__wwaaiittiinngg(());;
  24.           iinntt       ssbbuummppcc(());;
  25.           ssttrreeaammbbuuff**     sseettbbuuff((cchhaarr** ppttrr,, iinntt lleenn));;
  26.           ssttrreeaammppooss sseeeekkppooss((ssttrreeaammppooss,, iinntt ==iiooss::::iinn||iiooss::::oouutt));;
  27.           ssttrreeaammppooss sseeeekkooffff((ssttrreeaammooffff,, sseeeekk__ddiirr,, iinntt ==iiooss::::iinn||iiooss::::oouutt));;
  28.           iinntt       ssggeettcc(());;
  29.           iinntt       ssggeettnn((cchhaarr** ppttrr,, iinntt nn));;
  30.           iinntt       ssnneexxttcc(());;
  31.           iinntt       ssppuuttbbaacckkcc((cchhaarr));;
  32.           iinntt       ssppuuttcc((iinntt cc));;
  33.           iinntt       ssppuuttnn((ccoonnsstt cchhaarr** ss,, iinntt nn));;
  34.           vvooiidd      ssttoosssscc(());;
  35.           vviirrttuuaall iinntt    ssyynncc(());;
  36.      }};;
  37.  
  38. IIMMPPLLEEMMEENNTTAATTIIOONN
  39.      IRIX systems
  40.  
  41. DDEESSCCRRIIPPTTIIOONN
  42.      The ssttrreeaammbbuuff class supports buffers into which characters can be
  43.      inserted (put) or from which characters can be fetched (gotten).
  44.      Abstractly, such a buffer is a sequence of characters together with
  45.      one or two pointers (a get and/or a put pointer) that define the
  46.      location at which characters are to be inserted or fetched.  The
  47.      pointers should be thought of as pointing between characters rather
  48.      than at them.  This makes it easier to understand the boundary
  49.      conditions (a pointer before the first character or after the last).
  50.      Some of the effects of getting and putting are defined by this class
  51.      but most of the details are left to specialized classes derived from
  52.      ssttrreeaammbbuuff.  (See ffiilleebbuuff(3C), ssssbbuuff(3C), and ssttddiioobbuuff(3C).)
  53.  
  54.      Classes derived from ssttrreeaammbbuuff vary in their treatments of the get and
  55.      put pointers.  The simplest are unidirectional buffers which permit
  56.      only gets or only puts.  Such classes serve as pure sources
  57.      (producers) or sinks (consumers) of characters.  Queuelike buffers
  58.      (see ssttrrssttrreeaamm(3C) and ssssbbuuff(3C)) have a put and a get pointer which
  59.      move independently of each other.  In such buffers, characters that
  60.      are stored are held (queued) until they are later fetched.  Filelike
  61.      buffers (such as ffiilleebbuuff, see ffiilleebbuuff(3C)) permit both gets and puts
  62.      but have only a single pointer.  (An alternative description is that
  63.      the get and put pointers are tied together so that when one moves the
  64.      other also moves.)
  65.  
  66.      Most ssttrreeaammbbuuff member functions are organized into two phases.  As far
  67.      as possible, operations are performed inline by storing into or
  68.      fetching from arrays (the ggeett aarreeaa and the ppuutt aarreeaa, which together
  69.      form the rreesseerrvvee aarreeaa, or bbuuffffeerr).  From time to time, virtual
  70.      functions are called to deal with collections of characters in the get
  71.      and put areas.  That is, the virtual functions are called to fetch
  72.      more characters from the ultimate producer or to flush a collection of
  73.      characters to the ultimate consumer.  Generally, the user of a
  74.      ssttrreeaammbbuuff does not have to know anything about these details, but some
  75.      of the public members pass back information about the state of the
  76.      areas.  More information about these areas is provided in the
  77.      ssbbuuff..pprroott(3C) man page, which describes the protected interface.
  78.  
  79.      The following assumptions are made in the following descriptions of
  80.      the public member functions of the ssttrreeaammbbuuff class.
  81.  
  82.      * _i, _n, and _l_e_n are iinntts.
  83.  
  84.      * _c is an iinntt. It always holds a ``character'' value or EEOOFF.  A
  85.        ``character'' value is always positive even when cchhaarr is normally
  86.        sign extended.
  87.  
  88.      * _s_b and _s_b_1 are ssttrreeaammbbuuff**s.
  89.  
  90.      * _p_t_r is a cchhaarr**.
  91.  
  92.      * _o_f_f is a ssttrreeaammooffff.
  93.  
  94.      * _p_o_s is a ssttrreeaammppooss.
  95.  
  96.      * _d_i_r is a sseeeekk__ddiirr.
  97.  
  98.      * _m_o_d_e is an iinntt representing an ooppeenn__mmooddee.
  99.  
  100.      Public member functions:
  101.  
  102.      _i==_s_b-->>iinn__aavvaaiill(())
  103.           Returns the number of characters that are immediately available
  104.           in the get area for fetching.  _i characters may be fetched with a
  105.           guarantee that no errors will be reported.
  106.  
  107.      _i==_s_b-->>oouutt__wwaaiittiinngg(())
  108.           Returns the number of characters in the put area that have not
  109.           been consumed (by the ultimate consumer).
  110.  
  111.      _c==_s_b-->>ssbbuummppcc(())
  112.           Moves the get pointer forward one character and returns the
  113.           character it moved past.  Returns EEOOFF if the get pointer is
  114.           currently at the end of the sequence.
  115.  
  116.      _p_o_s==_s_b-->>sseeeekkooffff((_o_f_f,, _d_i_r,, _m_o_d_e))
  117.           Repositions the get and/or put pointers.  _m_o_d_e specifies whether
  118.           the put pointer (iiooss::::oouutt bit set) or the get pointer (iiooss::::iinn
  119.           bit set) is to be modified.  Both bits may be set in which case
  120.           both pointers should be affected.  _o_f_f is interpreted as a byte
  121.           offset.  (Notice that it is a signed quantity.)  The meanings of
  122.           possible values of _d_i_r are
  123.  
  124.           iiooss::::bbeegg
  125.                The beginning of the stream.
  126.  
  127.           iiooss::::ccuurr
  128.                The current position.
  129.  
  130.           iiooss::::eenndd
  131.                The end of the stream (end of file.)
  132.  
  133.      Not all classes derived from ssttrreeaammbbuuff support repositioning.
  134.      sseeeekkooffff(()) will return EEOOFF if the class does not support repositioning.
  135.      If the class does support repositioning, sseeeekkooffff(()) will return the new
  136.      position or EEOOFF on error.
  137.  
  138.      _p_o_s==_s_b-->>sseeeekkppooss((_p_o_s,, _m_o_d_e))
  139.           Repositions the streambuf get and/or put pointer to _p_o_s.  _m_o_d_e
  140.           specifies which pointers are affected as for sseeeekkooffff(()).  Returns
  141.           _p_o_s (the argument) or EEOOFF if the class does not support
  142.           repositioning or an error occurs.  In general a ssttrreeaammppooss should
  143.           be treated as a ``magic cookie'' and no arithmetic should be
  144.           performed on it.  The following two values have special meaning:
  145.  
  146.           ssttrreeaammppooss((00))
  147.                The beginning of the file.
  148.  
  149.           ssttrreeaammppooss((EEOOFF))
  150.                Used as an error indication.
  151.  
  152.      _c==_s_b-->>ssggeettcc(())
  153.           Returns the character after the get pointer.  Contrary to what
  154.           most people expect from the name IT DOES NOT MOVE THE GET
  155.           POINTER.  Returns EEOOFF if there is no character available.
  156.  
  157.      _s_b_1==_s_b-->>sseettbbuuff((_p_t_r,, _l_e_n,, _i))
  158.           Offers the _l_e_n bytes starting at _p_t_r as the reserve area.  If _p_t_r
  159.           is null or _l_e_n is zero or less, then an unbuffered state is
  160.           requested.  Whether the offered area is used, or a request for
  161.           unbuffered state is honored depends on details of the derived
  162.           class.  sseettbbuuff(()) normally returns _s_b, but if it does not accept
  163.           the offer or honor the request, it returns 0.
  164.  
  165.      _i==_s_b-->>ssggeettnn((_p_t_r,, _n))
  166.           Fetches the _n characters following the get pointer and copies
  167.           them to the area starting at _p_t_r.  When there are fewer than _n
  168.           characters left before the end of the sequence ssggeettnn(()) fetches
  169.           whatever characters remain.  ssggeettnn(()) repositions the get pointer
  170.           following the fetched characters and returns the number of
  171.           characters fetched.
  172.  
  173.      _c==_s_b-->>ssnneexxttcc(())
  174.           Moves the get pointer forward one character and returns the
  175.           character following the new position.  It returns EEOOFF if the
  176.           pointer is currently at the end of the sequence or is at the end
  177.           of the sequence after moving forward.
  178.  
  179.      _i==_s_b-->>ssppuuttbbaacckkcc((_c))
  180.           Moves the get pointer back one character.  _c must be the current
  181.           content of the sequence just before the get pointer.  The
  182.           underlying mechanism may simply back up the get pointer or may
  183.           rearrange its internal data structures so the _c is saved.  Thus
  184.           the effect of ssppuuttbbaacckkcc(()) is undefined if _c is not the character
  185.           before the get pointer.  ssppuuttbbaacckkcc(()) returns EEOOFF when it fails.
  186.           The conditions under which it can fail depend on the details of
  187.           the derived class.
  188.  
  189.      _i==_s_b-->>ssppuuttcc((_c))
  190.           Stores _c after the put pointer, and moves the put pointer past
  191.           the stored character; usually this extends the sequence.  It
  192.           returns EEOOFF when an error occurs.  The conditions that can cause
  193.           errors depend on the derived class.
  194.  
  195.      _i==_s_b-->>ssppuuttnn((_p_t_r,, _n))
  196.           Stores the _n characters starting at _p_t_r after the put pointer and
  197.           moves the put pointer past them.  ssppuuttnn(()) returns _i, the number
  198.           of characters stored successfully.  Usually, _i is _n, but it may
  199.           be less when errors occur.
  200.  
  201.      _s_b-->>ssttoosssscc(())
  202.           Moves the get pointer forward one character.  If the pointer
  203.           started at the end of the sequence this function has no effect.
  204.  
  205.      _i==_s_b-->>ssyynncc(())
  206.           Establishes consistency between the internal data structures and
  207.           the external source or sink.  The details of this function depend
  208.           on the derived class.  Usually this ``flushes'' any characters
  209.           that have been stored but not yet consumed, and ``gives back''
  210.           any characters that may have been produced but not yet fetched.
  211.           ssyynncc(()) returns EEOOFF to indicate errors.
  212.  
  213. CCAAVVEEAATTSS
  214.      sseettbbuuff does not really belong in the public interface.  It is there
  215.      for compatibility with the stream package.
  216.  
  217.      Requiring the program to provide the previously fetched character to
  218.      ssppuuttbbaacckk is probably a botch.
  219.  
  220. SSEEEE AALLSSOO
  221.      iiooss(3C), iissttrreeaamm(3C), oossttrreeaamm(3C), ssbbuuff..pprroott(3C)
  222.  
  223.      This man page is available only online.
  224.  
  225.